<!--
/**
 * @file Parser.html
 * @author Alejandro Dario Simi
 * @date $Date: 2013-07-11 21:02:48 +0000 (Thu, 11 Jul 2013) $
 *
 * $Id: Parser.html 95 2013-07-11 21:02:48Z daemonraco@gmail.com $
 * $URL: http://wcomix.googlecode.com/svn/tags/wcomix-1.0/docs/Parser.html $
 */
-->
<html>
	<head>
		<title>Parser</title>

		<script type="text/javascript" src="jquery-1.8.0.min.js"></script>

		<script type="text/javascript" src="SyntaxHighlighter/scripts/shCore.js"></script>
		<link type="text/css" rel="stylesheet" href="SyntaxHighlighter/styles/shCoreEclipse.css"/>
		<link type="text/css" rel="stylesheet" href="SyntaxHighlighter/styles/shThemeEclipse.css"/>
		<script type="text/javascript">SyntaxHighlighter.all();</script>

		<link rel="stylesheet" type="text/css" href="docs.css"/>
		<script type="text/javascript" src="docs.js"></script>
	</head>
	<body>
		<div class="Section">
			<span class="Title">Table Of Contents</span>
			<div class="TableOfContents"></div>
		</div>
		<div class="Section">
			<span class="Title">Themes</span>
			<div class="Paragraph">
				<p>Since wcomix is based on the themes, it provides a main class called [CL:WCParser] capable of reading and analyse a sort of pseudo-programing language.
				Such language is based in a series of tags and function with the logic to act on these tags.</p>
				<p>Basically, [CL:WCParser] has the avility to take a text file and return its contents modified by the function recuested in the text by
				the use of tags.</p>
				<p>The idea of using tags is to allow the possibility for the parser to run over any text without tags and leave it untouched.</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Tags</span>
			<div class="Paragraph">
				<p>When this parser runs over a text, it looks for two type of tags:<ul>
					<li><storng>&lt;:[ME:FUNC]:/&gt;</storng>: Opening tag.</li>
					<li><storng>&lt;::/&gt;</storng>: Closing tag.</li>
				</ul></p>
				<p>In this case, [ME:FUNC] is the identifier for the logic to use.</p>
				<p>From now on, all the text between both tags will be called "Content".</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Function</span>
			<div class="Paragraph">
				<p>This section will mention the list of available functions, their parameter and what they're capable of.</p>
			</div>
			
			<span class="SubTitle">IGNORE</span>
			<div class="Paragraph">
				<p>The function [ME:IGNORE] provides a way to write comments. Basically, when parser runs, it ignores this tag content.</p>
				<p>Alias:<ul>
					<li><strong>!</strong>: Is a short way to invoke this function.</li>
				</ul></p>
				<p>Examples:<ul>
					<li>
						<pre class="brush: wcparser;">&lt;:IGNORE:/&gt;
This is a comment.
&lt;::/&gt;</pre>
					</li>
					<li>
						<pre class="brush: wcparser;">&lt;:!:/&gt;
This is a comment using a short name for the function.
&lt;::/&gt;</pre>
					</li>
				</ul></p>
			</div>

			<span class="SubTitle">VAR</span>
			<div class="Paragraph">
				<p>This is the most simple function for the parser, it takes all it's content as the name of a assigned variable (see [L:#Variables::Variables] below)</p>
				<p>Parameters:<ul>
					<li><strong>!</strong>: When this parameter is set, if the variable is not assigned, this function generates no warning and ignores the sentence.</li>
				</ul></p>
				<p>Examples:<ul>
					<li>
						If the text been parsed needs the value of an assigned variable called "[VA:name]" it can be use similar to the next example
						<pre class="brush: wcparser;">&lt;div&gt;
	&lt;span&gt;The user &lt;:VAR:/&gt;name&lt;::/&gt; is logged in.&lt;/span&gt;
&lt;/div&gt;</pre>
					</li>
					<li>
						In the same way, if it's needed to display the last name and do nothing when it's not present it can be done like this:
						<pre class="brush: wcparser;">&lt;div&gt;
	&lt;strong&gt;Current User Surname&lt;/strong&gt;:
	&lt;span class="Surname"&gt;&lt;:VAR:!:/&gt;surname&lt;::/&gt;&lt;/span&gt;
&lt;/div&gt;</pre>
					</li>
				</ul></p>
			</div>

			<span class="SubTitle">INCLUDE</span>
			<div class="Paragraph">
				<p>This function allows to embed another text file. When its used, it takes its content as file path where the file to be embeded is
				stored. This file path must start with <strong>/</strong> (slash) and it will a path inside the templates' root path set be the method
				[L|http://docs.daemonraco.com/wcomix/doxy/de/def/class_w_c_parser.html#a5296018e54694d926c7f25ea88b1a853||{CL:WCParser}::{ME:templatesRoot()}].</p>
				<p>If the content doesn't start with a slash, it is considered to be the name of an assigned variable.</p>
				<p>Parameters:<ul>
					<li><strong>!</strong>: If the included file is not present or there is no content, it won't give any warning.</li>
					<li><strong>padding=<i>[VA:number]</i></strong>: This is a look and feel parameter which indicates that every line embeded has to be prefixed
					with as many TAB caracter as [VA:number].</li>
					<li><strong>over=<i>[VA:string]</i></strong>: When given, this parameter must always have the name of an assigned variable corresponding to an
					array. This is similar to function [L:#OVER::{ME:OVER}] without the parameter [VA:key].</li>
					<li><strong>full</strong>: When this parameter is set, ignores the templatesRoot configured and takes it's content as a system full path.</li>
					<li><strong>no-warnings</strong>: Disables all warnings generated inside the embeded text.</li>
					<li><strong>no-summary</strong>: Disables the summary of error generated for every parsed file.</li>
				</ul></p>
				<p>Examples:<ul>
					<li>
						Simply including a text file:
						<pre class="brush: wcparser;">&lt;div&gt;
&lt;:INCLUDE:/&gt;/boxes/search.html&lt;::/&gt;
&lt;/div&gt;</pre>
					</li>
					<li>
						Including a text file, if exists, and padding every line loaded from it with one Tab character:
						<pre class="brush: wcparser;">&lt;div&gt;
&lt;:INCLUDE:!:padding=1:/&gt;/boxes/ratings.html&lt;::/&gt;
&lt;/div&gt;</pre>
					</li>
					<li>
						Including a text file, if exists, where the file path is given by an assigned variable, padded by three Tab characters,
						and walking over an array:
						<pre class="brush: wcparser;">&lt;div&gt;
&lt;:INCLUDE:!:padding=3:over=images:/&gt;boxpath&lt;::/&gt;
&lt;/div&gt;</pre>
					</li>
				</ul></p>
			</div>


			<span class="SubTitle">ISSET</span>
			<div class="Paragraph">
				<p>This function allows to hide/show a piece of text when certain variable is assigned or not.</p>
				<p>Parameters:<ul>
					<li><strong>var=<i>[VA:string]</i></strong>: Name of the assigned variable to be considered.</li>
					<li><strong>!</strong>: Allow to show the content when the assigned variable is not set.</li>
				</ul></p>
				<p>Examples:<ul>
					<li>
						This example show a simple way of usage for this function:
						<pre class="brush: wcparser;">&lt;div&gt;
	&lt;span&gt;The variable 'MAXLEN' is
	&lt;:ISSET:var=MAXLEN:/&gt;set&lt;::/&gt;&lt;:ISSET:var=MAXLEN:!:/&gt;not set&lt;::/&gt;.&lt;/span&gt;
&lt;/div&gt;</pre>
					</li>
				</ul></p>
			</div>

			<span class="SubTitle">IF</span>
			<div class="Paragraph">
				<p>This function allows to hide/show a piece of the text depending on a condition. Such condition will always be the comparison of an
				assigned variable and a value represente by the paremeters [VA:value], [VA:to] or [VA:in].</p>
				<p>Parameters:<ul>
					<li><strong>!</strong>: Inverts the condition result</li>
					<li><strong>var=<i>[VA:string]</i></strong>: Name of the assigned variable to be analyzed.</li>
					<li><strong>value=<i>[VA:string]</i></strong>: Fixed value to be compared.<ul>
						<li><storng>Note</storng>: Preceds parameter [VA:to].</li>
					</ul></li>
					<li><strong>to=<i>[VA:string]</i></strong>: Name of an assigned variable which may have the same value than the assigned variable
					named in paramenter [VA:var].<ul>
						<li><storng>Note</storng>: Preceds parameter [VA:in].</li>
					</ul></li>
					<li><strong>in=<i>[VA:string]</i></strong>: Name of an assigned variable corresponding with an array. Such array may have an element
					with the value of the assigned variable named in paramenter [VA:var]. It is similar to the PHP function
					[L:http://php.net/manual/en/function.in-array.php::in_array()].</li>
					<li><strong>count=<i>[VA:number]</i></strong>: When the variable been checked and it is an array, it counts the elements and compare
					it with <strong>count<strong> returning true when equals. Otherwise, returns false.</li>
					</ul></p>
				<p>Examples:<ul>
					<li>
						Comparing a fixed value.
						<pre class="brush: wcparser">&lt;div&gt;
	&lt;span&gt;Wellcome&lt;:IF:!:var=visits:value=0:/&gt; again&lt;::/&gt; to out site.&lt;/span&gt;
&lt;/div&gt;</pre>
					</li>
				</ul></p>
			</div>

			<span class="SubTitle">OVER</span>
			<div class="Paragraph">
				<p>Over is a complex function that operates over an array and, for each element, it reparse it's content.</p>
				<p>By default, it walk on every element and use it as an associative subarray. This subarray is added as if it were a list of
				variables to be used for the reparsing of the content.</p>
				<p>When the elements of the array to walk over is only a simple list of values, this function must receive the parameter [VA:key] with
				a name. In this case, [ME:OVER] will reparse the content previously assign the current element to a variable with the name given by
				[VA:key]. Internally, this is called "simple mode".</p>
				<p>Parameters:<ul>
					<li><strong>list=[VA:string]</strong>: Name of an assigned variable corresponding with an array to be analyzed</li>
					<li><strong>key=[VA:string]</strong>: Name to assign in simple mode.</li>
				</ul></p>
				<p>Examples:<ul>
					<li>
						Supouse the next PHP code where the array is assigned (in the example, [VA:$parser] points to an instance of [CL:WCParser]):
						<pre class="brush: php;">$aux = array()
$aux[] = array(
	"name"	=> "Flower",
	"src"	=> "flower.png");
$aux[] = array(
	"name"	=> "Bread",
	"src"	=> "bread.png");

$parser->assign("food", $aux);
</pre>
						And now, supouse its usage like this:
						<pre class="brush: wcparser;">&lt;:OVER:list=food:/&gt;&lt;img src="&lt;:VAR:/&gt;src&lt;::/&gt;" title="&lt;:VAR:/&gt;name&lt;::/&gt;"/&gt;
&lt;::/&gt;</pre>
						This will return something like:
						<pre class="brush: xml;">&lt;img src="flower.png" title="Flower"/&gt;
&lt;img src="bread.png" title="Bread"/&gt;
</pre>
					</li>
				</ul></p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Variables</span>
			<div class="Paragraph">
				<p>Until this point, there were many mentions to "assigned variables" used from many puposes. These variables are set in [CL:WCParser]
				through the method [L|http://docs.daemonraco.com/wcomix/doxy/de/def/class_w_c_parser.html#adf6f9b7a403bb9594d2a3864a35b2cfc||{ME:assign()]}
				which associates a variable name with a value</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Inheritance</span>
			<div class="Paragraph">
				<p>For developers, it is posible to create new function to be parsed, or even to replace the standar functions. For this purpose, it is
				necessary to create a new class extending [L|http://docs.daemonraco.com/wcomix/doxy/d6/daa/class_w_c_parser_behavior.html||{CL:WCParserBehavior}]
				and adding the new class to a global desccriptor call [VA:$wcParserBehaviorMatrix].</p>
				<p>Such desccriptor can be modified in the next way:
				<pre class="brush: php;">$wcParserBehaviorMatrix["MYFUNCTION"] = "MyClass";</pre>
				</p>
				<p>Also, if the new class is a better way to solve the inclution of text files, something like this can be done:
				<pre class="brush: php;">$wcParserBehaviorMatrix["INCLUDE"] = "MyIncludeClass";</pre>
				</p>
			</div>
		</div>
	</body>
</html>